<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
    <head>
        <title>DSpace Documentation : Mirage Configuration and Customization</title>
	    <link rel="stylesheet" href="styles/site.css" type="text/css" />
        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">	    
    </head>

    <body>
	    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
		    <tr>
			    <td valign="top" class="pagebody">
				    <div class="pageheader">
					    <span class="pagetitle">
                            DSpace Documentation : Mirage Configuration and Customization
                                                    </span>
				    </div>
				    <div class="pagesubheading">
					    This page last changed on Mar 25, 2011 by <font color="#0050B2">peterdietz</font>.
				    </div>

				    <h1><a name="MirageConfigurationandCustomization-MirageThemeConfigurationandCustomization"></a>Mirage Theme Configuration and Customization</h1>

<style type='text/css'>/*<![CDATA[*/
div.rbtoc1301079432729 {margin-left: 0px;padding: 0px;}
div.rbtoc1301079432729 ul {list-style: none;margin-left: 0px;}
div.rbtoc1301079432729 li {margin-left: 0px;padding-left: 0px;}

/*]]>*/</style><div class='rbtoc1301079432729'>
<ul>
    <li><span class='TOCOutline'>1</span> <a href='#MirageConfigurationandCustomization-Introduction'>Introduction</a></li>
    <li><span class='TOCOutline'>2</span> <a href='#MirageConfigurationandCustomization-ConfigurationParameters'>Configuration Parameters</a></li>
    <li><span class='TOCOutline'>3</span> <a href='#MirageConfigurationandCustomization-TechnicalFeatures'>Technical Features</a></li>
<ul>
    <li><span class='TOCOutline'>3.1</span> <a href='#MirageConfigurationandCustomization-Look%26Feel'>Look &amp; Feel</a></li>
    <li><span class='TOCOutline'>3.2</span> <a href='#MirageConfigurationandCustomization-Structuralenhancementsforeasiercustomization.'>Structural enhancements for easier customization.</a></li>
    <li><span class='TOCOutline'>3.3</span> <a href='#MirageConfigurationandCustomization-EnhancedPerformance'>Enhanced Performance</a></li>
</ul>
    <li><span class='TOCOutline'>4</span> <a href='#MirageConfigurationandCustomization-Troubleshooting'>Troubleshooting</a></li>
<ul>
    <li><span class='TOCOutline'>4.1</span> <a href='#MirageConfigurationandCustomization-ErrorsusingHTTPS'>Errors using HTTPS</a></li>
</ul>
</ul></div>

<h2><a name="MirageConfigurationandCustomization-Introduction"></a>Introduction</h2>

<p>Mirage is a new XMLUI theme, added in DSpace 1.7 by <a href="http://www.atmire.com">@mire</a>. The code was mainly developed by <a href="mailto:art@atmire.com">Art Lowel</a>. The main benefits of Mirage are:</p>

<ul>
	<li>Clean new look and feel.</li>
	<li>Increased browser compatibility. The whole theme renders perfectly in today's modern browsers (Internet Explorer 7 and higher, Firefox, Safari, Chrome, ...)</li>
	<li>Easier to customize.</li>
	<li>Enhanced Performance</li>
</ul>


<h2><a name="MirageConfigurationandCustomization-ConfigurationParameters"></a>Configuration Parameters</h2>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'> Property: </td>
<td class='confluenceTd'> xmlui.theme.mirage.item-list.emphasis </td>
</tr>
<tr>
<td class='confluenceTd'> Example Value: </td>
<td class='confluenceTd'> xmlui.theme.mirage.item-list.emphasis = metadata <br class="atl-forced-newline" /> </td>
</tr>
<tr>
<td class='confluenceTd'> Informational Note: </td>
<td class='confluenceTd'> Determines which style should be used to display item lists. Allowed values:&nbsp; <br class="atl-forced-newline" />
<ul>
	<li><b>metadata</b>: includes item abstracts in the listing and is suited for scientific articles.</li>
	<li><b>file</b>: immediately shows you whether files are attached to the items, by displaying a large thumbnail icon for each of the items. <br class="atl-forced-newline" />
metadata is the default value. </li>
</ul>
</td>
</tr>
<tr>
<td class='confluenceTd'> Property: </td>
<td class='confluenceTd'> xmlui.theme.enableConcatenation <br class="atl-forced-newline" /> </td>
</tr>
<tr>
<td class='confluenceTd'> Example Value: </td>
<td class='confluenceTd'> xmlui.theme.enableConcatenation = false <br class="atl-forced-newline" /> </td>
</tr>
<tr>
<td class='confluenceTd'> Informational Note: </td>
<td class='confluenceTd'> Allows to enable concatenation for .js and .css files. Enhances performance when enabled by lowering the number of files that needs to be sent to the client per page request (as multiple files will be concatenated together and sent as one file). &nbsp;Value can be true or false. &nbsp;False by default. <br class="atl-forced-newline" /> </td>
</tr>
<tr>
<td class='confluenceTd'> Property: </td>
<td class='confluenceTd'> xmlui.theme.enableMinification <br class="atl-forced-newline" /> </td>
</tr>
<tr>
<td class='confluenceTd'> Example Value: </td>
<td class='confluenceTd'> xmlui.theme.enableMinification = false <br class="atl-forced-newline" /> </td>
</tr>
<tr>
<td class='confluenceTd'> Informational Note: </td>
<td class='confluenceTd'> Allows to enable minification for .js and .css files. Enhances performance when enabled by removing unnecessary whitespaces and other characters, thus reducing the size of files to be sent. &nbsp;Value can be true or false. &nbsp;False by default. <br class="atl-forced-newline" /> </td>
</tr>
</tbody></table>
</div>



<h2><a name="MirageConfigurationandCustomization-TechnicalFeatures"></a>Technical Features</h2>

<h3><a name="MirageConfigurationandCustomization-Look%26Feel"></a>Look &amp; Feel</h3>

<ul>
	<li>The Simple Item Display underwent a full redesign to provide visitors with a clearer overview of available metadata and associated files.</li>
	<li><b>Item list views</b> can now be displayed in two distinct different styles. Switching between these styles is possible with the new dspace.cfg parameter 'xmlui.theme.mirage.item-list.emphasis'
	<ul>
		<li>The <b>'metadata'</b> list style includes item abstracts in the listing and is suited for scientific articles.</li>
		<li>The <b>'file'</b> list style immediately shows you whether files are attached to the items, by displaying a large thumbnail icon for each of the items.</li>
	</ul>
	</li>
</ul>


<h3><a name="MirageConfigurationandCustomization-Structuralenhancementsforeasiercustomization."></a>Structural enhancements for easier customization.</h3>

<ul>
	<li><b>Based on the new restructured dri2xhtml base templates</b>. Templates in the theme, overriding the new base templates, are located in the same folder hierarchy to ensure full transparency.</li>
	<li><b>Automated browser feature detection</b> for improved browser compatibility.
	<ul>
		<li>In other themes, user agent detection is used to identify which browser version your user is using. Based on the result of this detection, the theme would use a different cascaded style sheet (CSS) to render a compatible page for the visitor. This approach has 2 major issues:
		<ul>
			<li>User agent detection isn't very reliable</li>
			<li>Maintaining these different CSS files is a maintenance nightmare for developers, especially when using features from newer browsers.</li>
		</ul>
		</li>
		<li>Mirage applies two novel techniques to resolve these issues
		<ul>
			<li>For compatibility with older Internet Explorer browsers, <a href="http://paulirish.com/2008/conditional-stylesheets-vs-css-hacks-answer-neither/">conditional comments give the body tag a class corresponding to the version of IE</a></li>
			<li><a href="http://www.modernizr.com/">modernizr</a> is used to detect which css features are available in the user's browser. This way you can  target all browsers that support a certain feature using css classes, and rules affecting the same element can be put together in the same  place for all browsers.</li>
		</ul>
		</li>
	</ul>
	</li>
	<li><b>CSS files are now split up according to function</b> instead of browser. <b>style.css</b> will now fit most needs for customization. Following additional CSS files are included, but will rarely need to be changed:
	<ul>
		<li><b>reset.css</b> ensures that browser-specific initializations are being reset.</li>
		<li><b>base.css</b> contains a few base styles</li>
		<li><b>helper.css</b> contains helper classes to deal with specific functionality.</li>
		<li><b>handheld.css and print.css</b> enable you to define styles for handheld devices and printing of pages.</li>
	</ul>
	</li>
	<li><b>jQuery and jQueryUI are included by default</b>. To avoid conflicts the authority control javascript has been rewritten to use jQuery instead  of Prototype and Script.aculo.us.</li>
</ul>


<h3><a name="MirageConfigurationandCustomization-EnhancedPerformance"></a>Enhanced Performance</h3>

<ul>
	<li><b>Concatenation and</b> <b><a href="http://en.wikipedia.org/wiki/Minification_%28programming%29">Minification</a></b> <b>techniques</b> for css and js files.
	<ul>
		<li>The IncludePageMeta has been extended to generate URL's to the concatenated version of all css files using the same media tag.</li>
		<li>The ConcatenationReader has been created to return concatenated and minified versions of the css and js files.</li>
		<li>Once js and css files have been minified and concatenated, they are being properly cached. As a result, the minification and concatenation operations only need to happen once, and do not include performance overhead.</li>
		<li>Caution: when minification is enabled, all code-comments will be removed. This could be a problem for comments containing copyright  notices, so for files with those comments you should disable minification by adding '?nominify' after the url e.g.
<br class="atl-forced-newline" />
&lt;map:parameter name="javascript" value="lib/js/jquery-ui-1.8.5.custom.min.js?nominify"/&gt;
<br class="atl-forced-newline" /></li>
		<li>Disabled by default, these features need to be enabled in the configuration using the properties 'xmlui.theme.enableConcatenation' and  'xmlui.theme.enableMinification'</li>
		<li>These features can be enabled for other themes as well, but will require an alteration of the theme's sitemap.</li>
	</ul>
	</li>
	<li>Javascript references are included at the bottom of the page instead of the top. This optimizes page load times in general.
<br class="atl-forced-newline" /></li>
</ul>


<h2><a name="MirageConfigurationandCustomization-Troubleshooting"></a>Troubleshooting</h2>

<h3><a name="MirageConfigurationandCustomization-ErrorsusingHTTPS"></a>Errors using HTTPS</h3>

<p>DSpace 1.7.0 ships with a hardcoded http:// link for JQuery, causing problems for users running 1.7.0 Mirage on HTTPS. While awaiting the implementation of this fix in an upcoming release, you can solve in the following file: <b>lib/core/page-structure.xsl</b>, <b>addJavascript</b> template. In this file, you will need to <b>replace</b></p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">&lt;script type=<span class="code-quote">"text/javascript"</span> src=<span class="code-quote">"http:<span class="code-comment">//ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"</span>&gt;&amp;#160;&lt;/script&gt;</span>
</pre>
</div></div>

<p>with</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">        &lt;script type=<span class="code-quote">"text/javascript"</span>&gt;
            &lt;xsl:text disable-output-escaping=<span class="code-quote">"yes"</span>&gt;<span class="code-keyword">var</span> JsHost = ((<span class="code-quote">"https:"</span> == document.location.protocol) ? <span class="code-quote">"https:<span class="code-comment">//"</span> : <span class="code-quote">"http://"</span>);
</span>            document.write(unescape(<span class="code-quote">"%3Cscript src='"</span> + JsHost + <span class="code-quote">"ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js' type='text/javascript'%3E%3C/script%3E"</span>));&lt;/xsl:text&gt;
        &lt;/script&gt;
</pre>
</div></div>

<p>Thanks Peter Dietz for providing this fix. Note: This issue is resolved in 1.7.1</p>

				    
                    			    </td>
		    </tr>
	    </table>
	    <table border="0" cellpadding="0" cellspacing="0" width="100%">
			<tr>
				<td height="12" background="https://wiki.duraspace.org/images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td>
			</tr>
		    <tr>
			    <td align="center"><font color="grey">Document generated by Confluence on Mar 25, 2011 19:21</font></td>
		    </tr>
	    </table>
    </body>
</html>